package com.jiashihui.web.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author jiashihui
 * @describe: swagger2
 * @date 2019/01/29  http://127.0.0.1:8091/swagger-ui.html
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * Flag to enable or disable possibly loaded using a property file
     */
    @Value("${swagger.enable}")
    private boolean enableSwagger;

    /**
     * .groupName("商品接口文档")   设置栏目名
     * .select()  初始化并返回一个API选择构造器
     * .paths(PathSelectors.any()) 设置路径筛选
     * .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.goods.controller"))  添加路径选择条件
     * .build();构建
     *
     * PathSelectors类的方法：
     * 　Predicate<String> any():满足条件的路径，该断言总为true
     * 　Predicate<String> none():不满足条件的路径,该断言总为false  (生产环境可以屏蔽掉swagger)
     * 　Predicate<String> regex(final String pathRegex):符合正则的路径
     *
     * RequestHandlerSelectors类的方法：
     * 　Predicate<RequestHandler> any()：返回包含所有满足条件的请求处理器的断言，该断言总为true
     * 　Predicate<RequestHandler> none()：返回不满足条件的请求处理器的断言,该断言总为false
     * 　Predicate<RequestHandler> basePackage(final String basePackage)：返回一个断言(Predicate)，该断言包含所有匹配basePackage下所有类的请求路径的请求处理器
     *
     * .@Api()用于类； 表示标识这个类是swagger的资源
     * .@ApiOperation()用于方法； 表示一个http请求的操作
     * .@ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）
     * .@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收
     * .@ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改
     * .@ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略
     * .@ApiImplicitParam() 用于方法 表示单独的请求参数
     * .@ApiImplicitParams() 用于方法，包含多个
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jiashihui.web"))
                .paths(PathSelectors.any())
                //.paths(PathSelectors.regex("/dept/.*"))//设置访问路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("swagger2测试")
                .termsOfServiceUrl("http://localhost:8091/")
                .contact("JiaShiHui")
                .version("1.0")
                .build();
    }
}

/**
 * @ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
 * @ApiModelProperty：用在属性上，描述响应类的属性
 *
 * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
    · header --> 请求参数的获取：@RequestHeader
    · query --> 请求参数的获取：@RequestParam
    · path（用于restful接口）--> 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用）
    dataType：参数类型，默认String，其它值dataType="Integer"
    defaultValue：参数的默认值
 */
